/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.catalina;

import org.apache.catalina.deploy.NamingResources;

/**
 * A <code>Server</code> element represents the entire Catalina servlet
 * container. Its attributes represent the characteristics of the servlet
 * container as a whole. A <code>Server</code> may contain one or more
 * <code>Services</code>, and the top level set of naming resources.
 * <p>
 * Normally, an implementation of this interface will also implement
 * <code>Lifecycle</code>, such that when the <code>start()</code> and
 * <code>stop()</code> methods are called, all of the defined
 * <code>Services</code> are also started or stopped.
 * <p>
 * In between, the implementation must open a server socket on the port number
 * specified by the <code>port</code> property. When a connection is accepted,
 * the first line is read and compared with the specified shutdown command. If
 * the command matches, shutdown of the server is initiated.
 * <p>
 * <strong>NOTE</strong> - The concrete implementation of this class should
 * register the (singleton) instance with the <code>ServerFactory</code> class
 * in its constructor(s).
 * 
 * @author Craig R. McClanahan
 * @version $Revision: 467222 $ $Date: 2006-10-24 11:17:11 +0800 (星期二, 24 十月
 *          2006) $
 */

public interface Server {

	// ------------------------------------------------------------- Properties

	/**
	 * Return descriptive information about this Server implementation and the
	 * corresponding version number, in the format
	 * <code>&lt;description&gt;/&lt;version&gt;</code>.
	 */
	public String getInfo();

	/**
	 * Return the global naming resources.
	 */
	public NamingResources getGlobalNamingResources();

	/**
	 * Set the global naming resources.
	 * 
	 * @param globalNamingResources
	 *            The new global naming resources
	 */
	public void setGlobalNamingResources(NamingResources globalNamingResources);

	/**
	 * Return the port number we listen to for shutdown commands.
	 */
	public int getPort();

	/**
	 * Set the port number we listen to for shutdown commands.
	 * 
	 * @param port
	 *            The new port number
	 */
	public void setPort(int port);

	/**
	 * Return the shutdown command string we are waiting for.
	 */
	public String getShutdown();

	/**
	 * Set the shutdown command we are waiting for.
	 * 
	 * @param shutdown
	 *            The new shutdown command
	 */
	public void setShutdown(String shutdown);

	// --------------------------------------------------------- Public Methods

	/**
	 * Add a new Service to the set of defined Services.
	 * 
	 * @param service
	 *            The Service to be added
	 */
	public void addService(Service service);

	/**
	 * Wait until a proper shutdown command is received, then return.
	 */
	public void await();

	/**
	 * Return the specified Service (if it exists); otherwise return
	 * <code>null</code>.
	 * 
	 * @param name
	 *            Name of the Service to be returned
	 */
	public Service findService(String name);

	/**
	 * Return the set of Services defined within this Server.
	 */
	public Service[] findServices();

	/**
	 * Remove the specified Service from the set associated from this Server.
	 * 
	 * @param service
	 *            The Service to be removed
	 */
	public void removeService(Service service);

	/**
	 * Invoke a pre-startup initialization. This is used to allow connectors to
	 * bind to restricted ports under Unix operating environments.
	 * 
	 * @exception LifecycleException
	 *                If this server was already initialized.
	 */
	public void initialize() throws LifecycleException;
}
